Shareware Super Platinum 8

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Super Platinum 8 / Shareware Super Platinum 8.iso / mac / PROGTOOL / TDOOR201.ZIP;1 / TRIDOOR.DOC < prev next >

Wrap

Text File | 1994-02-04 | 28.8 KB | 1,387 lines

TriDoor Version 2.0 Copyright (c) 1992-1994 By TriSoft TriDoor i COPYRIGHT NOTICE ---------------- TriDoor is a copyrighted program being distributed under the shareware concept. As such you may use TriDoor for a period of 30 days without registering the software. After the 30 day evaluation period, you must register your copy of TriDoor or you will be in violation of United States and International copyright laws. As a shareware program, TriDoor may be freely distributed through a BBS. Shareware distributors may distribute copies of TriDoor on disk for a modest disk duplication charge not to exceed $6 per disk. TriDoor ii WARRANTY -------- TriDoor is distributed without warranty. In no event will TriSoft be liable to you for damages, including any loss of profits, lost savings, or other incidental or consequential damages arising out of your use of or inability to use the program, even if TriSoft or an authorized representative has been advised of the possibility of such damages. TriSoft will not be liable for any such claim by any other party. TriDoor iii TABLE OF CONTENTS ----------------- INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 USING TRIDOOR . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 RUNNING A TRIDOOR DOOR . . . . . . . . . . . . . . . . . . . . . . 3 SPECIAL KEYS . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 THE TRIDOOR VARIABLES . . . . . . . . . . . . . . . . . . . . . . . 5 TDAlias . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 TDAnsiColor . . . . . . . . . . . . . . . . . . . . . . . . . 5 TDBaudRate . . . . . . . . . . . . . . . . . . . . . . . . . . 5 TDBBSName . . . . . . . . . . . . . . . . . . . . . . . . . . 5 TDCityState . . . . . . . . . . . . . . . . . . . . . . . . . 5 TDDoorName . . . . . . . . . . . . . . . . . . . . . . . . . . 5 TDDropToDOS . . . . . . . . . . . . . . . . . . . . . . . . . 5 TDErrorCorrecting . . . . . . . . . . . . . . . . . . . . . . 6 TDNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 TDLockedBaudRate . . . . . . . . . . . . . . . . . . . . . . . 6 TDMinutesLeft . . . . . . . . . . . . . . . . . . . . . . . . 6 TDNonStandardIRQ . . . . . . . . . . . . . . . . . . . . . . . 6 TDPhoneNumber . . . . . . . . . . . . . . . . . . . . . . . . 6 TDSecurityLevel . . . . . . . . . . . . . . . . . . . . . . . 6 TDSerialPort . . . . . . . . . . . . . . . . . . . . . . . . . 6 TDSysopName . . . . . . . . . . . . . . . . . . . . . . . . . 7 TDUserFirstName . . . . . . . . . . . . . . . . . . . . . . . 7 TDUserName . . . . . . . . . . . . . . . . . . . . . . . . . . 7 THE TRIDOOR FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . 8 TDBeepRemote . . . . . . . . . . . . . . . . . . . . . . . . . 8 TDClrScr . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 TDDetectANSI . . . . . . . . . . . . . . . . . . . . . . . . . 8 TDDetectRIPScrip . . . . . . . . . . . . . . . . . . . . . . . 8 TDDisplayFile . . . . . . . . . . . . . . . . . . . . . . . . 8 TDDisplayBreakableFile . . . . . . . . . . . . . . . . . . . . 8 TDGetBackground . . . . . . . . . . . . . . . . . . . . . . . 8 TDGetch . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 TDGetForeground . . . . . . . . . . . . . . . . . . . . . . . 9 TDGets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 TDGotoXY . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 TDInitialize . . . . . . . . . . . . . . . . . . . . . . . . . 9 TDKeyPressed . . . . . . . . . . . . . . . . . . . . . . . . . 9 TDHangUp . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 TDPrintf . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 TDPutch . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 TDPuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 TDSetColor . . . . . . . . . . . . . . . . . . . . . . . . . . 10 TDTimeLeft . . . . . . . . . . . . . . . . . . . . . . . . . . 11 TriDoor iv TDTimeOn . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 ADVANCED SERIAL COMMUNICATIONS ROUTINES . . . . . . . . . . . . . . 12 TDCommClose . . . . . . . . . . . . . . . . . . . . . . . . . 12 TDCommKeyPressed . . . . . . . . . . . . . . . . . . . . . . . 12 TDCommModemString . . . . . . . . . . . . . . . . . . . . . . 12 TDCommOpen . . . . . . . . . . . . . . . . . . . . . . . . . . 12 TDCommPutch . . . . . . . . . . . . . . . . . . . . . . . . . 13 TDCommPuts . . . . . . . . . . . . . . . . . . . . . . . . . . 13 TDCommSetBaudRate . . . . . . . . . . . . . . . . . . . . . . 13 TDCommSetDataFormat . . . . . . . . . . . . . . . . . . . . . 13 TDCommSetDTR . . . . . . . . . . . . . . . . . . . . . . . . . 13 TDCommSetFIFO . . . . . . . . . . . . . . . . . . . . . . . . 13 TDCommSetPort . . . . . . . . . . . . . . . . . . . . . . . . 14 SUPPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 REGISTRATION . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 TriDoor 1 INTRODUCTION ------------ TriDoor is a comprehensive set of Borland C++, Microsoft C/C++, Symantec C++, Turbo C++, and Watcom C/C++ (the 16-bit version of the compiler only) functions designed to enable programmers to easily write doors for BBSes. The following are some of TriDoor's many features: Assembly language serial input/output routines for maximum speed. Fully supports high speed modems: 16550 FIFO buffering and locked serial ports. Built in ANSI terminal emulator. No need to have ANSI.SYS loaded in memory. Optional detection of RIPScrip graphics. TriDoor is DesqView aware. Supports all of the most popular door data file formats: TriBBS, PCBoard, GAP (DOOR.SYS), Spitfire, WildCat!, RBBS, and WWIV. Thus, a door built around TriDoor is compatible with a wide range of BBS software. TriDoor 2 USING TRIDOOR ------------- TriDoor is supplied with the following shareware versions of the TriDoor library. ====================================================================== Compiler Library ---------------------------------------------------------------------- Borland C++ BCTDOOR.LIB Microsoft C/C++ MCTDOOR.LIB Symantec C++ SCTDOOR.LIB Turbo C++ TCTDOOR.LIB Watcom C/C++ WCTDOOR.LIB ====================================================================== Because TriDoor comes supplied as a library it can be seamlessly integrated with your door program by simply including the name of the library either in the door program's project file or in the command line that you use to compile the program. Additionally, you should include TriDoor's header file (TRIDOOR.H) in all your door program's source code files. Please note that the TriDoor libraries are compiled using the large memory model; therefore, your door programs much be compiled using the large memory model too. To initialize the TriDoor door driver routines, you must always call TriDoor's TDInitialize function at the start of your program. The TDInitialize function must be called before your program makes any calls to any of TriDoor's other functions. TriDoor 3 RUNNING A TRIDOOR DOOR ---------------------- A TriDoor-based door program is run by entering a command similar to the following: door config nonstandardirq In the above command line, "door" is the name of your door's EXE file and the "config" parameter is the name of the door's configuration file. The configuration file can have any name the sysop chooses, but it must reside in the same directory as the door. The configuration file is an ASCII text file with the following format: Line 1: Door data file type. Line 2: Path to the door data file(s). Line 3: BBS name. Line 4: Sysop's name. Line 5: Locked baud rate. As illustrated above, the door's data file type is specified in line 1 and can be PCB for PCBoard, GAP for GAP (DOOR.SYS), SF for Spitfire, RBBS for RBBS, WC for WildCat!, TRIBBS for TriBBS, or WWIV for WWIV. The locked baud rate is specified in line 5. If the sysop doesn't lock his serial port, he must specify 0 for the locked baud rate. NOTE: Although many door formats do pass the locked baud rate in the door data files, some older formats such as RBBS do not. For conformity, TriDoor requires that you specify the locked baud rate in line 5 and ignores any value passed in the door data files. The following is a sample door configuration file: TRIBBS C:\TRIBBS\ The Lobster Buoy Mark Goodwin 38400 The "nonstandardirq" parameter is used to specify a nonstandard IRQ for the serial port. The legitimate range of values is from 0 to 15. TriDoor can be run locally without a door data file (handy for the sysop to use the door without logging on to the BBS) by specifying LOCAL after the configuration file parameter in the DOS command line. TriDoor will request the user to enter his name before running the door. TriDoor 4 SPECIAL KEYS ------------ While a door is running, the sysop can press certain special keys to perform a variety of functions. The following is a list of the functions that the TriDoor special keys perform: Key(s) Function HOME Toggles between the user status window and a help display that lists the TriDoor special keys. F6 Takes 5 minutes away from the caller. NOTE: This will NOT be returned to BBS. F7 Gives 5 minutes to the caller. NOTE: This will NOT be returned to the BBS. F9 Quit the door and return the caller to the BBS. F10 Enter chat mode. Pressing the ESC key exits the chat mode. Alt+D Drop to DOS. TriDoor 5 THE TRIDOOR VARIABLES --------------------- The following are the global variables that TriDoor supplies for the door author's convenience: char TDAlias[81]; The TDAlias variable holds the caller's alias. Note: This variable will be set to the user's name for PCB, RBBS, WC, and SF. int TDAnsiColor; The TDAnsiColor variable is set to 1 for a caller using ANSI color graphics or to 0 for a monochrome caller. long TDBaudRate; The TDBaudRate variable holds the caller's baud rate. This is the caller's actual connection rate and not the locked baud rate. NOTE: TriDoor will set TDBaudRate to 0 for local calls. char TDBBSName[81]; The TDBBSName variable holds the BBS's name. char TDCityState[81]; The TDCityState variable holds the user's city and state. This may not be supported by all door formats and will be set to a null string if not. char TDDoorName[81]; The TDDoorName variable holds the door's name. The door's name will be displayed in the user status window. NOTE: It is the door author's responsibility to assign a value to this variable. void (*TDDropToDOS)(void); This is a pointer to a user-defined drop to DOS function. This is not required in order for TriDoor to drop to DOS; however, this function is a hook so that the door program can implement such advanced features as swapping the door out of memory, etc. TriDoor 6 int TDErrorCorrecting; The TDErrorCorrecting variable will be set to 1 if there is an error correcting connection. Otherwise, this variable will be set to 0 to indicate a nonerror correcting connection. Note: This variable will be always be set to 0 for RBBS and WWIV. int TDNode; The TDNode variable holds the caller's node number. Note: This variable will always be set to 1 for RBBS and WWIV. long TDLockedBaudRate; The TDLockedBaudRate variable holds the serial port's locked baud rate, if any. int TDMinutesLeft; The TDMinutesLeft variable holds the number of minutes the caller had remaining when he entered the door. int TDNonStandardIRQ; The TDNonStandardIRQ variable holds the number for a nonstandard IRQ if one was passed on the door's command line. Otherwise, TDNonStandardIRQ will be equal to 0. char TDPhoneNumber[81]; The TDPhoneNumber variable holds the user's phone number. This may not be supported by all door formats and will be set to a null string if not. int TDSecurityLevel; The TDSecurityLevel variable holds the caller's security level. int TDSerialPort; The TDSerialPort variable holds the number of the serial port. TriDoor 7 char TDSysopName[81]; The TDSysopName variable holds the sysop's name. char TDUserFirstName[81]; The TDUserFirstName variable holds the user's first name. char TDUserName[81]; The TDUserName variable holds the user's name. TriDoor 8 THE TRIDOOR FUNCTIONS --------------------- The following is a explanation of the functions that TriDoor provides: void TDBeepRemote(void); The TDBeepRemote will send a BELL (0x7) to the remote terminal only. void TDClrScr(void); The TDClrScr function clears both the local and remote displays. int TDDetectANSI(void); The TDDetectANSI function will try to detect if the remote caller's terminal supports ANSI terminal emulation. TDDetectANSI will return TRUE if it successfully detects ANSI terminal emulation. Otherwise, the TDDetectANSI function will return FALSE. int TDDetectRIPScrip(void); The TDDetectRIPScrip function will try to detect if the remote caller's terminal supports RIPScrip graphics emulation. TDDetectRIPScrip will return TRUE if it successfully detects RIPScrip terminal emulation. Otherwise, the TDDetectRIPScrip function will return FALSE. void TDDisplayFile(char *file); The TDDisplayFile function displays the file specified by the "file" parameter 22 lines at a time. void TDDisplayBreakableFile(char *file); The TDDisplayBreakableFile function displays the file specified by the "file" parameter 22 lines at a time. If the user presses <SPACE> at any time, TriDoor will skip displaying the remainder of the file. int TDGetBackground(void); The TDGetBackground function returns the current background color. TriDoor 9 int TDGetch(void); The TDGetch function waits for either a key to be pressed or a character to come in through the serial port. As soon as a character is available, its value will be returned by TDGetch. Extended keypresses are returned as 256 + the key's scan code. int TDGetForeground(void); The TDGetForeground function returns the current foreground color. char *TDGets(char *string, int length); The TDGets function returns a string that if entered either locally or remotely. The string's location is pointed to by the "string" parameter. The maximum string that TDGets will allow to be determined by "length" - 1. void TDGotoXY(int x, int y); The TDGotoXY procedure positions the cursor for both the local and remote displays. The cursor's new column position is specified by the "x" parameter and its new row position is specified by the "y" parameter. NOTE: This will only work if the user has ANSI enabled. TriDoor will ignore this statement if called when the user does not have ANSI enabled. void TDInitialize(int argc, char *argv[]); The TDInitialize function initializes the TriDoor door driver routines. This function must be called before you use any other TriDoor functions in your program. You must pass the main function's argc and argv parameters to TDInitialize function's parameters. int TDKeyPressed(void); The TDKeyPressed function indicates if a key has been pressed locally or a character has been received remotely. If a character is ready, the TDKeyPressed function will return a value of TRUE. Otherwise, the TDKeyPressed function will return a value of FALSE to indicate that a character isn't available. void TDHangUp(void); The TDHangUp function disconnects the connection by first trying to drop the DTR line. If that is unsuccessful, the TDHangUp function TriDoor 10 will terminate the connection with an ATH0 command. int TDPrintf(char *s, ...); The TDPrintf function acts identically like the C runtime library printf function except it sends the output to both the local display screen and to the remote caller. void TDPutch(int c); The TDPutch function sends the character specified by the "c" parameter to both the local display and to the remote caller. void TDPuts(char *s); The TDPuts function sends the string specified by the "s" parameter to both the local display and to the remote caller. int TDSetColor(int f, int b); The TDSetColor procedure sets the foreground color (the "f" parameter) and the background color (the "b" parameter) for both the local and remote displays. NOTE: The colors will only be set if the caller has ANSI color graphics enabled. The foreground colors are as follows: 0 - Black 1 - Blue 2 - Green 3 - Cyan 4 - Red 5 - Magenta 6 - Brown 7 - White 8 - Dark grey 9 - Light blue 10 - Light green 11 - Light cyan 12 - Light red 13 - Light magenta 14 - Yellow 15 - Bright white The background colors are as follows: 0 - Black 1 - Blue 2 - Green 3 - Cyan TriDoor 11 4 - Red 5 - Magenta 6 - Brown 7 - White 8 - Black with blinking foreground 9 - Blue with blinking foreground 10 - Green with blinking foreground 11 - Cyan with blinking foreground 12 - Red with blinking foreground 13 - Magenta with blinking foreground 14 - Yellow with blinking foreground 15 - White with blinking foreground The following constants are defined in TRIDOOR.H to make it easier to specify color values: 0 - BLACK 1 - BLUE 2 - GREEN 3 - CYAN 4 - RED 5 - MAGENTA 6 - BROWN 7 - LIGHTGRAY 8 - DARKGRAY 9 - LIGHTBLUE 10 - LIGHTGREEN 11 - LIGHTCYAN 12 - LIGHTRED 13 - LIGHTMAGENTA 14 - YELLOW 15 - WHITE int TDTimeLeft(void); The TDTimeLeft function returns the number of minutes the caller has remaining. int TDTimeOn(void); The TDTimeOn function returns the number of minutes that the caller has been in the door. TriDoor 12 ADVANCED SERIAL COMMUNICATIONS ROUTINES --------------------------------------- This section documents the advanced serial communications routines that TriDoor has to offer. You should note that the use of these is strictly optional. By default, the TDInitialize routine performs all of the set up of the serial port and TriDoor will automatically close the serial port when TriDoor exists from memory. However, door authors will probably find many uses for these routines for such doors as callback verifiers, etc. Basically, if you don't have a specific reason for using these functions, stay away from them. They are very low-level and 99% of all doors can be written just fine without them. void TDCommClose(void); The TDCommClose function closes a previously opened serial port. int TDCommGetch(void); The TDCommGetch function returns a character from the serial port's buffer. int TDCommIsCarrier(void); The TDCommIsCarrier function returns TRUE if carrier is present. Otherwise, TDCommIsCarrier returns FALSE to indicate that carrier isn't present. int TDCommKeyPressed(void); The TDCommKeyPressed function returns TRUE if a key is available in the serial port's input buffer. Otherwise, TDCommKeyPressed returns FALSE to indicate that carrier isn't present. void TDCommModemString(char *string); The TDCommModemString is used to send characters to the modem. It has a slight delay between characters, recognizes the <~> character as a half-second delay, and recognizes any character preceded by a <^> as a control character (i.e., ^M would be a carriage return). void TDCommOpen(int port); The TDCommOpen function is used to open a specified serial "port". The serial port must be in the range of 1 to 4. If a nonstandard IRQ is to be used, the TDNonStandardIRQ must be set to an appropriate TriDoor 13 value. NOTE: The TDCommOpen function is automatically opened by TDInitialize; therefore, the TDCommOpen function should only be closed if the door has previously closed the active serial port with the TDCommClose function. void TDCommPutch(int c); The TDCommPutch function sends the character specified by the "c" parameter out the serial port. void TDCommPuts(char *string); The TDCommPuts function sends the string specified by the "string" parameter out the serial port. void TDCommSetBaudRate(long rate); The TDCommSetBaudRate function sets the baud rate to the speed specified by the "rate" parameter. void TDCommSetDataFormat(int bits, int parity, int stopbits); The TDCommSetDataFormat function sets the serial port for the number of bits specified by the "bits" parameter (should be 7 or 8), the parity specified by the "parity" parameter (should be NO_PARITY, EVEN_PARITY, or ODD_PARITY), and the number of stop bits specified by the "stopbits" parameter (should be 0 or 1). void TDCommSetDTR(int flag); The TDCommSetDTR function is used to set the serial port's DTR line. The new setting for the DTR line is specified by the "flag" parameter and can be either TRUE or FALSE. void TDCommSetFIFO(int trigger); The TDCommSetFIFO function sets the interrupt trigger level for a 16550 UART's FIFO buffers. The trigger level can be set for 1, 4, 8, or 14 and is specified as the "trigger" parameter. If any other trigger level is specified, the FIFO buffers will be disabled. You should note that this function has no effect if the serial port doesn't have a 16550 UART. TriDoor 14 void TDCommSetPort(long rate, int bits, int parity, int stopbits); The TDCommSetPort function sets the serial port for the baud rate specified by the "rate" parameter, the number of bits specified by the "bits" parameter (should be 7 or 8), the parity specified by the "parity" parameter (should be NO_PARITY, EVEN_PARITY, or ODD_PARITY), and the number of stop bits specified by the "stopbits" parameter (should be 0 or 1). TriDoor 15 SUPPORT ------- You may obtain assistance with a TriDoor related problem by calling The Lobster Buoy at 207-941-0805. TriDoor 16 REGISTRATION ------------ Registration of TriDoor is only $25.00. Please use the form in the file REGISTER.TXT. When you register TriDoor, you will receive a disk with registered versions the TriDoor libraries for all of the supported compilers.